# HG changeset patch # User Rik # Date 1355768623 28800 # Node ID 01d4f742d75de87518d4e94e06a286d05ef92482 # Parent 420b5603cbbfb5c11f1e9d2c9f5a7a1f26c2f4be doc: Re-organize and improve Java Interface documentation. * doc/interpreter/java.txi: Add usejava, isjava functions, debug_java, java_matrix_autoconversion, java_unsigned_autoconversion to docs. Re-organize to put functions in logical order. Add new "Dialog Box Functions" node. * doc/interpreter/system.txi: Remove usejava from list of system functions. * libinterp/octave-value/ov-java.cc(FjavaObject, FjavaMethod, Fjava_unsigned_autoconversion): Improve docstrings. * scripts/java/javaArray.m: Tweak docstring. * scripts/java/listdlg.m: Wrap long lines in docstring. Improve code example in docstring. diff -r 420b5603cbbf -r 01d4f742d75d doc/interpreter/java.txi --- a/doc/interpreter/java.txi Mon Dec 17 10:16:08 2012 -0800 +++ b/doc/interpreter/java.txi Mon Dec 17 10:23:43 2012 -0800 @@ -26,19 +26,56 @@ @cindex calling Octave from Java @cindex Octave, calling from Java -The Java Interface is designed for calling Java functions from Octave. -If you want to do the reverse and call Octave from Java, you might try +The Java Interface is designed for calling Java functions from within Octave. +If you want to do the reverse, and call Octave from within Java, try a library like @code{javaOctave} (@url{http://kenai.com/projects/javaOctave}) or @code{joPas} (@url{http://jopas.sourceforge.net}). @menu -* Available Functions:: +* Java Interface Functions:: +* Dialog Box Functions:: * FAQ - Frequently asked Questions:: @end menu -@node Available Functions -@section Available Functions +@node Java Interface Functions +@section Java Interface Functions + +The following functions are the core of the Java Interface. They provide +a way to create a Java object, get and set its data fields, and call Java +methods which return results to Octave. + +@cindex object, creating a Java object +@DOCSTRING(javaObject) + +@cindex fields, displaying available fields of a Java object +FIXME: Need documentation on how fieldnames() is overloaded to return +the methods of a Java object. + +@cindex field, returning value of Java object field +FIXME: Need documentation on how to use structure-like indexing +to get fields from Java object. + +@cindex field, setting value of Java object field +FIXME: Need documentation on how to use structure-like indexing +to set fields from Java object. + +@DOCSTRING(isjava) + +@cindex array, creating a Java array +@DOCSTRING(javaArray) + +@cindex method, invoking a method of a Java object +@DOCSTRING(javaMethod) + +@cindex methods, displaying available methods of a Java object +FIXME: Need documentation on how methods() is overloaded to return +the methods of a Java object. + +The following three functions are used to display and modify the +class path used by the Java Virtual Machine. This is entirely separate +from Octave's PATH variable and is used by the JVM to find the correct +code to execute. @cindex classpath, displaying @cindex classpath, dynamic @@ -58,33 +95,22 @@ @cindex path, removing from classpath @DOCSTRING(javarmpath) +The following four functions provide information and control over the interface +between Octave and the Java Virtual Machine. + +@DOCSTRING(usejava) + @cindex memory, displaying Java memory status @DOCSTRING(javamem) -@cindex array, creating a Java array -@DOCSTRING(javaArray) +@DOCSTRING(java_matrix_autoconversion) -@cindex object, creating a Java object -@DOCSTRING(javaObject) - -@cindex method, invoking a method of a Java object -@DOCSTRING(javaMethod) +@DOCSTRING(java_unsigned_autoconversion) -@cindex field, returning value of Java object field -FIXME: Need documentation on how to use structure-like indexing -to get fields from Java object. - -@cindex field, setting value of Java object field -FIXME: Need documentation on how to use structure-like indexing -to set fields from Java object. +@DOCSTRING(debug_java) -@cindex methods, displaying available methods of a Java object -FIXME: Need documentation on how methods() is overloaded to return -the methods of a Java object. - -@cindex fields, displaying available fields of a Java object -FIXME: Need documentation on how fieldnames() is overloaded to return -the methods of a Java object. +@node Dialog Box Functions +@section Dialog Box Functions The following functions all use the Java Interface to provide some form of dialog box. diff -r 420b5603cbbf -r 01d4f742d75d doc/interpreter/system.txi --- a/doc/interpreter/system.txi Mon Dec 17 10:16:08 2012 -0800 +++ b/doc/interpreter/system.txi Mon Dec 17 10:23:43 2012 -0800 @@ -521,8 +521,6 @@ @DOCSTRING(octave_config_info) -@DOCSTRING(usejava) - @DOCSTRING(getrusage) @node Hashing Functions diff -r 420b5603cbbf -r 01d4f742d75d libinterp/octave-value/ov-java.cc --- a/libinterp/octave-value/ov-java.cc Mon Dec 17 10:16:08 2012 -0800 +++ b/libinterp/octave-value/ov-java.cc Mon Dec 17 10:23:43 2012 -0800 @@ -1879,9 +1879,8 @@ return retval; } -#endif -// endif on HAVE_JAVA -// +#endif // endif on HAVE_JAVA + // DEFUN blocks below must be outside of HAVE_JAVA block so that // documentation strings are always available, even when functions are not. @@ -1892,7 +1891,7 @@ Create a Java object of class @var{classsname}, by calling the class\n\ constructor with the arguments @var{arg1}, @dots{}\n\ \n\ -The first example creates an uninitialized object,\n\ +The first example below creates an uninitialized object,\n\ while the second example supplies an initial argument to the constructor.\n\ \n\ @example\n\ @@ -1942,8 +1941,8 @@ "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {@var{ret} =} javaMethod (@var{methodname}, @var{obj})\n\ @deftypefnx {Built-in Function} {@var{ret} =} javaMethod (@var{methodname}, @var{obj}, @var{arg1}, @dots{})\n\ -Invoke the method @var{methodname} on the Java object @var{obj} with the arguments\n\ -@var{arg1}, @dots{} For static methods, @var{obj} can be a string\n\ +Invoke the method @var{methodname} on the Java object @var{obj} with the\n\ +arguments @var{arg1}, @dots{} For static methods, @var{obj} can be a string\n\ representing the fully qualified name of the corresponding class. The\n\ function returns the result of the method invocation.\n\ \n\ @@ -2194,9 +2193,9 @@ @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\ +converted when @code{java_matrix_autoconversion} is enabled. When enabled,\n\ +Java arrays of class Byte or Integer are converted to matrices of class\n\ +uint8 or uint32 respectively. The default value is true.\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\ @@ -2236,7 +2235,7 @@ } // Outside of #ifdef HAVE_JAVA because it is desirable to be able to -// merely test for the presence of a Java object without having Java installed. +// test for the presence of a Java object without having Java installed. DEFUN (isjava, args, , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} isjava (@var{x})\n\ diff -r 420b5603cbbf -r 01d4f742d75d scripts/java/javaArray.m --- a/scripts/java/javaArray.m Mon Dec 17 10:16:08 2012 -0800 +++ b/scripts/java/javaArray.m Mon Dec 17 10:23:43 2012 -0800 @@ -30,6 +30,8 @@ ## if @var{classname} is a reference type, or to a default value (usually 0) ## if @var{classname} is a primitive type. ## +## Sample code: +## ## @example ## @group ## jary = javaArray ("java.lang.String", 2, 2); diff -r 420b5603cbbf -r 01d4f742d75d scripts/java/listdlg.m --- a/scripts/java/listdlg.m Mon Dec 17 10:16:08 2012 -0800 +++ b/scripts/java/listdlg.m Mon Dec 17 10:23:43 2012 -0800 @@ -64,10 +64,10 @@ ## ## @example ## @group -## [sel, ok] = listdlg ("ListString", @{"An item", "another", "yet another"@}, "SelectionMode", "Multiple" ); +## [sel, ok] = listdlg ("ListString", @{"An item", "another", "yet another"@}, +## "SelectionMode", "Multiple"); ## if (ok == 1) -## imax = numel (sel); -## for i = 1:1:imax +## for i = 1:numel (sel) ## disp (sel(i)); ## endfor ## endif