# HG changeset patch
# User Rik <rik@octave.org>
# Date 1355723032 28800
# Node ID d9b8333df5e48ea8f11850edb2e587cfaf30c8e8
# Parent  d0579fed7e227396880ceffd39be4336f2d6608f
Deprecate java_debug, java_convert_matrix, java_unsigned_conversion.
Replace with debug_java, java_matrix_autoconversion, java_unsigned_autoconversion.

* libinterp/octave-value/ov-java.h: Rename Vjava_debug,
Vjava_unsigned_conversion, Vjava_convert_matrix to Vdebug_java,
Vjava_unsigned_autoconversion, Vjava_matrix_autoconversion.

* libinterp/octave-value/ov-java.cc(Fjava_debug, Fjava_unsigned_conversion,
Fjava_convert_matrix): Rename functions to match variables in ov-java.h.
Improve docstrings.

* scripts/deprecated/module.mk: Add java_debug.m, java_convert_matrix.m,
java_unsigned_conversion.m files to build system.

* scripts/deprecated/java_convert_matrix.m: New m-file for deprecated function.

* scripts/deprecated/java_debug.m: New m-file for deprecated function.

* scripts/deprecated/java_unsigned_conversion.m: New m-file for deprecated function.

diff --git a/libinterp/octave-value/ov-java.cc b/libinterp/octave-value/ov-java.cc
--- a/libinterp/octave-value/ov-java.cc
+++ b/libinterp/octave-value/ov-java.cc
@@ -84,9 +84,9 @@
 static int octave_java_refcount = 0;
 static long octave_thread_ID = -1;
 
-bool Vjava_convert_matrix = false;
-bool Vjava_unsigned_conversion = true;
-bool Vjava_debug = false;
+bool Vjava_matrix_autoconversion = false;
+bool Vjava_unsigned_autoconversion = true;
+bool Vdebug_java = false;
 
 class JVMArgs
 {
@@ -130,7 +130,7 @@
             if (line.length () > 2
                 && (line.find ("-D") == 0 || line.find ("-X") == 0))
               java_opts.push_back (line);
-            else if (line.length () > 0 && Vjava_debug)
+            else if (line.length () > 0 && Vdebug_java)
               std::cerr << "invalid JVM option, skipping: " << line << std::endl;
           }
       }
@@ -163,7 +163,7 @@
         vm_args.options = new JavaVMOption [vm_args.nOptions];
         for (std::list<std::string>::const_iterator it = java_opts.begin (); it != java_opts.end (); ++it)
           {
-            if (Vjava_debug)
+            if (Vdebug_java)
               std::cout << *it << std::endl;
             vm_args.options[index++].optionString = strsave ((*it).c_str ());
           }
@@ -630,7 +630,7 @@
 
   if (ex)
     {
-      if (Vjava_debug)
+      if (Vdebug_java)
         jni_env->ExceptionDescribe ();
 
       jni_env->ExceptionClear ();
@@ -967,7 +967,7 @@
         }
     }
 
-  if (retval.is_undefined () && Vjava_convert_matrix)
+  if (retval.is_undefined () && Vjava_matrix_autoconversion)
     {
       cls = find_octave_class (jni_env, "org/octave/Matrix");
 
@@ -998,7 +998,7 @@
             }
           else if (s == "byte")
             {
-              if (Vjava_unsigned_conversion)
+              if (Vjava_unsigned_autoconversion)
                 {
                   uint8NDArray m (dims);
                   mID = jni_env->GetMethodID (cls, "toByte", "()[B");
@@ -1017,7 +1017,7 @@
             }
           else if (s == "integer")
             {
-              if (Vjava_unsigned_conversion)
+              if (Vjava_unsigned_autoconversion)
                 {
                   uint32NDArray m (dims);
                   mID = jni_env->GetMethodID (cls, "toInt", "()[I");
@@ -1191,7 +1191,7 @@
       //jcls = jni_env->FindClass ("java/lang/Object");
       jcls = 0;
     }
-  else if (!Vjava_convert_matrix
+  else if (!Vjava_matrix_autoconversion
            && ((val.is_real_matrix ()
                 && (val.rows () == 1 || val.columns () == 1))
                || val.is_range ()))
@@ -1203,7 +1203,7 @@
       jobj = dv;
       jcls = jni_env->GetObjectClass (jobj);
     }
-  else if (Vjava_convert_matrix
+  else if (Vjava_matrix_autoconversion
            && (val.is_matrix_type () || val.is_range ()) && val.is_real_type ())
     {
       jclass_ref mcls (jni_env, find_octave_class (jni_env, "org/octave/Matrix"));
@@ -2166,50 +2166,71 @@
 #endif
 }
 
-DEFUN (java_convert_matrix, args, nargout,
+DEFUN (java_matrix_autoconversion, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} java_convert_matrix ()\n\
-FIXME: Determine what this variable controls and rename function\n\
-Query or set the internal variable that determines FIXME.\n\
-@seealso{java_unsigned_conversion, java_debug}\n\
+@deftypefn  {Built-in Function} {@var{val} =} java_matrix_autoconversion ()\n\
+@deftypefnx {Built-in Function} {@var{old_val} =} java_matrix_autoconversion (@var{new_val})\n\
+@deftypefnx {Built-in Function} {} java_matrix_autoconversion (@var{new_val}, \"local\")\n\
+Query or set the internal variable that controls whether Java arrays are\n\
+automatically converted to Octave matrices.  The default value is false.\n\
+\n\
+When called from inside a function with the \"local\" option, the variable is\n\
+changed locally for the function and any subroutines it calls.  The original\n\
+variable value is restored when exiting the function.\n\
+@seealso{java_unsigned_autoconversion, debug_java}\n\
 @end deftypefn")
 {
 #ifdef HAVE_JAVA
-  return SET_INTERNAL_VARIABLE (java_convert_matrix);
+  return SET_INTERNAL_VARIABLE (java_matrix_autoconversion);
 #else
-  error ("java_convert_matrix: Octave was not compiled with Java interface");
+  error ("java_matrix_autoconversion: Octave was not compiled with Java interface");
   return octave_value ();
 #endif
 }
 
-DEFUN (java_unsigned_conversion, args, nargout,
+DEFUN (java_unsigned_autoconversion, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} java_unsigned_conversion ()\n\
-FIXME: Determine what this variable controls and rename function\n\
-Query or set the internal variable that determines FIXME.\n\
-@seealso{java_convert_matrix, java_debug}\n\
+@deftypefn  {Built-in Function} {@var{val} =} java_unsigned_autoconversion ()\n\
+@deftypefnx {Built-in Function} {@var{old_val} =} java_unsigned_autoconversion (@var{new_val})\n\
+@deftypefnx {Built-in Function} {} java_unsigned_autoconversion (@var{new_val}, \"local\")\n\
+Query or set the internal variable that controls how integer classes are\n\
+converted when Java matrix autoconversion is enabled.  When enabled, Java\n\
+arrays of class Byte or Integer are converted to matrices of class uint8 or\n\
+uint32 respectively.\n\
+\n\
+When called from inside a function with the \"local\" option, the variable is\n\
+changed locally for the function and any subroutines it calls.  The original\n\
+variable value is restored when exiting the function.\n\
+@seealso{java_matrix_autoconversion, debug_java}\n\
 @end deftypefn")
 {
 #ifdef HAVE_JAVA
-  return SET_INTERNAL_VARIABLE (java_unsigned_conversion);
+  return SET_INTERNAL_VARIABLE (java_unsigned_autoconversion);
 #else
-  error ("java_unsigned_conversion: Octave was not compiled with Java interface");
+  error ("java_unsigned_autoconversion: Octave was not compiled with Java interface");
   return octave_value ();
 #endif
 }
 
-DEFUN (java_debug, args, nargout,
+DEFUN (debug_java, args, nargout,
   "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} java_debug ()\n\
-FIXME: Determine what this variable controls and rename function\n\
-Query or set the internal variable that determines FIXME.\n\
-@seealso{java_convert_matrix, java_unsigned_conversion}\n\
+@deftypefn  {Built-in Function} {@var{val} =} debug_java ()\n\
+@deftypefnx {Built-in Function} {@var{old_val} =} debug_java (@var{new_val})\n\
+@deftypefnx {Built-in Function} {} debug_java (@var{new_val}, \"local\")\n\
+Query or set the internal variable that determines whether extra debugging\n\
+information regarding the initialization of the JVM and any Java exceptions\n\
+is printed.\n\
+\n\
+When called from inside a function with the \"local\" option, the variable is\n\
+changed locally for the function and any subroutines it calls.  The original\n\
+variable value is restored when exiting the function.\n\
+@seealso{java_matrix_autoconversion, java_unsigned_autoconversion}\n\
 @end deftypefn")
 {
 #ifdef HAVE_JAVA
-  return SET_INTERNAL_VARIABLE (java_debug);
+  return SET_INTERNAL_VARIABLE (debug_java);
 #else
-  error ("java_debug: Octave was not compiled with Java interface");
+  error ("debug_java: Octave was not compiled with Java interface");
   return octave_value ();
 #endif
 }
diff --git a/libinterp/octave-value/ov-java.h b/libinterp/octave-value/ov-java.h
--- a/libinterp/octave-value/ov-java.h
+++ b/libinterp/octave-value/ov-java.h
@@ -109,11 +109,11 @@
 unbox (JNIEnv* jni_env, const octave_value_list& args,
        jobjectArray_ref& jobjs, jobjectArray_ref& jclss);
 
-extern JAVAPKG_API bool Vjava_convert_matrix;
+extern JAVAPKG_API bool Vjava_matrix_autoconversion;
 
-extern JAVAPKG_API bool Vjava_unsigned_conversion;
+extern JAVAPKG_API bool Vjava_unsigned_autoconversion;
 
-extern JAVAPKG_API bool Vjava_debug;
+extern JAVAPKG_API bool Vdebug_java;
 
 class JAVAPKG_API octave_java : public octave_base_value
 {
diff --git a/scripts/deprecated/java_convert_matrix.m b/scripts/deprecated/java_convert_matrix.m
new file mode 100644
--- /dev/null
+++ b/scripts/deprecated/java_convert_matrix.m
@@ -0,0 +1,48 @@
+## Copyright (C) 2012 Rik Wehbring
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn  {Built-in Function} {@var{val} =} java_convert_matrix ()
+## @deftypefnx {Built-in Function} {@var{old_val} =} java_convert_matrix (@var{new_val})
+## @deftypefnx {Built-in Function} {} java_convert_matrix (@var{new_val}, \"local\")
+## Query or set the internal variable that controls whether Java arrays are
+## automatically converted to Octave matrices.  The default value is false.
+## 
+## When called from inside a function with the \"local\" option, the variable is
+## changed locally for the function and any subroutines it calls.  The original
+## variable value is restored when exiting the function.
+## @seealso{java_matrix_autoconversion, java_unsigned_conversion, java_debug}
+## @end deftypefn
+
+function old_val = java_convert_matrix (varargin)
+
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "java_convert_matrix is obsolete and will be removed from a future version of Octave; use java_matrix_autoconversion instead");
+  endif
+
+  if (nargin > 2)
+    print_usage ();
+  endif
+
+  old_val = java_matrix_autoconversion (varargin{:});
+
+endfunction
+
diff --git a/scripts/deprecated/java_debug.m b/scripts/deprecated/java_debug.m
new file mode 100644
--- /dev/null
+++ b/scripts/deprecated/java_debug.m
@@ -0,0 +1,49 @@
+## Copyright (C) 2012 Rik Wehbring
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn  {Built-in Function} {@var{val} =} java_debug ()
+## @deftypefnx {Built-in Function} {@var{old_val} =} java_debug (@var{new_val})
+## @deftypefnx {Built-in Function} {} java_debug (@var{new_val}, \"local\")
+## Query or set the internal variable that determines whether extra debugging
+## information regarding the initialization of the JVM and any Java exceptions
+## is printed.
+## 
+## When called from inside a function with the \"local\" option, the variable is
+## changed locally for the function and any subroutines it calls.  The original
+## variable value is restored when exiting the function.
+## @seealso{debug_java, java_convert_matrix, java_unsigned_conversion}
+## @end deftypefn
+
+function old_val = java_debug (varargin)
+
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "java_debug is obsolete and will be removed from a future version of Octave; use debug_java instead");
+  endif
+
+  if (nargin > 2)
+    print_usage ();
+  endif
+
+  old_val = debug_java (varargin{:});
+
+endfunction
+
diff --git a/scripts/deprecated/java_unsigned_conversion.m b/scripts/deprecated/java_unsigned_conversion.m
new file mode 100644
--- /dev/null
+++ b/scripts/deprecated/java_unsigned_conversion.m
@@ -0,0 +1,50 @@
+## Copyright (C) 2012 Rik Wehbring
+##
+## This file is part of Octave.
+##
+## Octave is free software; you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 3 of the License, or (at
+## your option) any later version.
+##
+## Octave is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+## General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with Octave; see the file COPYING.  If not, see
+## <http://www.gnu.org/licenses/>.
+
+## -*- texinfo -*-
+## @deftypefn  {Built-in Function} {@var{val} =} java_unsigned_conversion ()
+## @deftypefnx {Built-in Function} {@var{old_val} =} java_unsigned_conversion (@var{new_val})
+## @deftypefnx {Built-in Function} {} java_unsigned_conversion (@var{new_val}, \"local\")
+## Query or set the internal variable that controls how integer classes are
+## converted when Java matrix autoconversion is enabled.  When enabled, Java
+## arrays of class Byte or Integer are converted to matrices of class uint8 or
+## uint32 respectively.
+## 
+## When called from inside a function with the \"local\" option, the variable is
+## changed locally for the function and any subroutines it calls.  The original
+## variable value is restored when exiting the function.
+## @seealso{java_unsigned_autoconversion, java_convert_matrix, debug_java}
+## @end deftypefn
+
+function old_val = java_unsigned_conversion (varargin)
+
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "java_unsigned_conversion is obsolete and will be removed from a future version of Octave; use java_unsigned_autoconversion instead");
+  endif
+
+  if (nargin > 2)
+    print_usage ();
+  endif
+
+  old_val = java_unsigned_autoconversion (varargin{:});
+
+endfunction
+
diff --git a/scripts/deprecated/module.mk b/scripts/deprecated/module.mk
--- a/scripts/deprecated/module.mk
+++ b/scripts/deprecated/module.mk
@@ -5,11 +5,14 @@
   deprecated/cor.m \
   deprecated/corrcoef.m \
   deprecated/cut.m \
+  deprecated/java_debug.m \
   deprecated/error_text.m \
   deprecated/isstr.m \
+  deprecated/java_convert_matrix.m \
   deprecated/java_get.m \
   deprecated/java_invoke.m \
   deprecated/java_new.m \
+  deprecated/java_unsigned_conversion.m \
   deprecated/java_set.m \
   deprecated/javafields.m \
   deprecated/javamethods.m \