# HG changeset patch
# User Ernst Reissner <rei3ner@arcor.de>
# Date 1487386710 -3600
#      Sat Feb 18 03:58:30 2017 +0100
# Node ID 66e84d9b70e12c56b8945f4ab02669c4a33ab1d8
# Parent  a9f72f9200d42bc17b28f028b9c236593bf74527
partial fix of bug #50299: Java interface: Ordering and Headlines

diff -r a9f72f9200d4 -r 66e84d9b70e1 doc/interpreter/external.txi
--- a/doc/interpreter/external.txi	Sat Feb 18 00:05:26 2017 +0100
+++ b/doc/interpreter/external.txi	Sat Feb 18 03:58:30 2017 +0100
@@ -1804,10 +1804,10 @@
 or @code{joPas} (@url{http://jopas.sourceforge.net/}).
 
 @menu
-* Making Java Classes Available::2
-* Creating an Instance of a Java Class::3
-* Handling Java Memory Limitations::4
-* Java Interface Functions::1
+* Making Java Classes Available::
+* How to use Java from within Octave::
+* Passing parameters to the JVM::
+* Java Interface Functions::
 @end menu
 
 
@@ -1926,23 +1926,194 @@
 @end example
 
 @c ------------------------------------------------------------------------
-@node Creating an Instance of a Java Class
-@subsection Creating an Instance of a Java Class
+@node How to use Java from within Octave
+@subsection How to use Java from within Octave
 @c - index -
 @cindex object, how to create
 @cindex instance, how to create
 @c - index -
 
-The function @code{javaObject} can be used to create Java objects.
-
-Example:
+The function @code{javaObject} is to create java objects. 
+In fact it invokes the public constructor of the class with the given name 
+with the given parameters. 
+
+The following example shows how to invoke 
+the constructors @code{BigDecimal(double)} and @code{BigDecimal(String)} 
+of the  java class @code{java.math.BigDecimal}. 
 
 @example
-Passenger = javaObject ("package.FirstClass", row, seat);
+oneD = javaObject ("java.math.BigDecimal",  1.001 );
+oneS = javaObject ("java.math.BigDecimal", "1.001");
 @end example
 
-@node Handling Java Memory Limitations
-@subsection Handling Java Memory Limitations
+Note that for parameters the octave type @code{double} 
+is implicitly converted into the java type @code{double} 
+and the octave type (array of) @code{char} 
+is converted into the java type @code{String}. 
+The java object created by @code{javaObject} 
+is never automatically converted into an octave type 
+but remains a java object. 
+It can be assigned to an octave variable. 
+
+@example
+d=1.001;
+ondD = javaObject ("java.math.BigDecimal", d);
+@end example
+
+We can check whether this is a java-object 
+and we can also determine the class. 
+
+@example
+isjava(d) % yields ans = 0
+class(d)  % yields ans = double
+isjava(oneD) % yields ans = 1
+class(oneD)  % yields ans = java.math.BigDecimal
+@end example
+
+
+We now modify our example above a little bit 
+
+@example
+d=javaObject ("java.lang.Double",  1.001 )
+ondD = javaObject ("java.math.BigDecimal", d);
+@end example
+
+We can check whether this is a java-object 
+and we can also determine the class. 
+
+@example
+isjava(d) % yields ans = 1
+class(d)  % yields ans = java.lang.Double
+isjava(oneD) % yields ans = 1
+class(oneD)  % yields ans = java.math.BigDecimal
+@end example
+
+Here we can see, that even @code{java.lang.Double} is not converted to
+an octave @code{double} if created by @code{javaObject}. 
+On the other hand, as parameter of a constructor (or a method), the java classes 
+@code{java.lang.Double} and @code{double} can be converted into one another. 
+Be careful with this feature because there may be ambiguities. 
+
+
+Via @code{javaObject} one may create all kinds of java objects but arrays. 
+The latter are created through @code{javaArray}. 
+
+
+
+We can even invoke public member methods on @code{oneD} in java style: 
+
+@example
+oneD.toString % yields ans = 1.000999999999999889865...
+oneS.toString % yields ans = 1.001
+@end example
+
+The first result may be surprinsing 
+but simply comes from the fact, 
+that @code{1.001} cannot be exactly represented as a double number 
+which is not visible for @code{double} because it is rounded before
+output. 
+Note that unlike in java, 
+in octave methods without arguments can be invoked with and without
+@code{()}. 
+
+
+
+While in matlab it is possible to invoke even static methods with a java
+like syntax, this is not possible in octave. 
+Instead, one has to use the function @code{javaMethod} 
+as in the following example. 
+
+@example
+java.math.BigDecimal.valueOf(1.001) % works in matlab but not in octave 
+javaMethod("valueOf", "java.math.BigDecimal", 1.001) % works for both 
+@end example
+
+Note that for methods and for constructors, 
+parameters are converted automatically between octave types and java types 
+if appropriate. 
+For methods this is also true with return values, whereas for
+constructors this is not. 
+
+Here is an example which shows 
+that the java class @code{java.math.BigDecimal} is indeed useful. 
+Compare the output of the following lines. 
+
+@example
+javaObject("java.math.BigDecimal","1")\
+.divide(javaObject("java.math.BigDecimal","1000000"))\
+.multiply(javaObject("java.math.BigDecimal","1000001"))\
+.toString()
+1/1000000*1000001
+@end example
+
+
+It is also possible to access public fields of java objects from within octave 
+with a java-like grammar. 
+Matlab allows that kind of access also for static fields, 
+whereas in octave one must use according functions. 
+
+@example
+java.math.BigDecimal.ONE % works for matlab but not for octave 
+java_get("java.math.BigDecimal", "ONE") % works for both 
+@end example
+
+Accordingly, with @code{java_set} the value of a field can be set. 
+Note that only public java fields are accessible from within octave. 
+
+
+The following example indicates, that in octave @code{[]} represents java's @code{null} value. 
+
+@example
+javaObject ("java.math.BigDecimal", []);
+% yields error: [java] java.lang.NullPointerException
+@end example
+
+This shows by the way, 
+how octave represents exceptions and errors in java. 
+
+Note that it is dangerous to represent java's @code{null} value 
+by octave's @code{[]}, 
+because @code{null} has no type whereas @code{[]} has type @code{double}. 
+
+
+There are also octave functions providing limited java reflection: 
+
+@example
+fieldnames (oneD)
+methods (oneD)
+@end example
+
+list the public fields and methods of @code{oneD}, 
+both static or not, but only if public. 
+
+
+Finally we show how to access the stack trace from within octave. 
+Function @code{debug_java} is to set and to get the debug state: 
+
+Here an example with @code{debug_java} reset: 
+
+@example
+debug_java() % yields 0
+javaObject("java.math.BigDecimal","1")
+.divide(javaObject("java.math.BigDecimal", "0")) 
+% yields an exception without stacktrace 
+@end example
+
+Here an example with @code{debug_java} set: 
+
+@example
+debug_java(true)
+debug_java() % yields 1
+javaObject("java.math.BigDecimal","1")
+.divide(javaObject("java.math.BigDecimal", "0")) 
+% yields an exception with stacktrace 
+@end example
+
+
+
+
+@node Passing parameters to the JVM
+@subsection Passing parameters to the JVM
 @cindex memory, limitations
 
 In order to execute Java code Octave creates a Java Virtual Machine (JVM).
@@ -2158,142 +2329,5 @@
 @DOCSTRING(java_unsigned_autoconversion)
 
 @DOCSTRING(debug_java)
-@node Java Interface Functions
-@subsection 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 array, creating a Java array
-@DOCSTRING(javaArray)
-
-There are many different variable types in Octave, but only ones created
-through @code{javaObject} can use Java functions.  Before using Java with an
-unknown object the type can be checked with @code{isjava}.
-
-@DOCSTRING(isjava)
-
-Once an object has been created it is natural to find out what fields the
-object has, and to read (get) and write (set) them.
-
-@cindex fields, displaying available fields of a Java object
-In Octave the @code{fieldnames} function for structures has been overloaded
-to return the fields of a Java object.  For example:
-
-@example
-@group
-dobj = javaObject ("java.lang.Double", pi);
-fieldnames (dobj)
-@result{}
-@{
-  [1,1] = public static final double java.lang.Double.POSITIVE_INFINITY
-  [1,2] = public static final double java.lang.Double.NEGATIVE_INFINITY
-  [1,3] = public static final double java.lang.Double.NaN
-  [1,4] = public static final double java.lang.Double.MAX_VALUE
-  [1,5] = public static final double java.lang.Double.MIN_NORMAL
-  [1,6] = public static final double java.lang.Double.MIN_VALUE
-  [1,7] = public static final int java.lang.Double.MAX_EXPONENT
-  [1,8] = public static final int java.lang.Double.MIN_EXPONENT
-  [1,9] = public static final int java.lang.Double.SIZE
-  [1,10] = public static final java.lang.Class java.lang.Double.TYPE
-@}
-@end group
-@end example
-
-@cindex field, returning value of Java object field
-The analogy of objects with structures is carried over into reading and writing
-object fields.  To read a field the object is indexed with the @samp{.}
-operator from structures.  This is the preferred method for reading fields, but
-Octave also provides a function interface to read fields with @code{java_get}.
-An example of both styles is shown below.
-
-@example
-@group
-dobj = javaObject ("java.lang.Double", pi);
-dobj.MAX_VALUE
-@result{}  1.7977e+308
-java_get ("java.lang.Float", "MAX_VALUE")
-@result{}  3.4028e+38
-@end group
-@end example
-
-@DOCSTRING(java_get)
-
-@cindex field, setting value of Java object field
-@DOCSTRING(java_set)
-
-@cindex methods, displaying available methods of a Java object
-To see what functions can be called with an object use @code{methods}.  For
-example, using the previously created @var{dobj}:
-
-@example
-@group
-methods (dobj)
-@result{}
-Methods for class java.lang.Double:
-boolean equals(java.lang.Object)
-java.lang.String toString(double)
-java.lang.String toString()
-@dots{}
-@end group
-@end example
-
-To call a method of an object the same structure indexing operator @samp{.} is
-used.  Octave also provides a functional interface to calling the methods of an
-object through @code{javaMethod}.  An example showing both styles is shown
-below.
-
-@example
-@group
-dobj = javaObject ("java.lang.Double", pi);
-dobj.equals (3)
-@result{}  0
-javaMethod ("equals", dobj, pi)
-@result{}  1
-@end group
-@end example
-
-@cindex method, invoking a method of a Java object
-@DOCSTRING(javaMethod)
-
-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
-@env{PATH} variable and is used by the JVM to find the correct code to execute.
-
-@cindex classpath, displaying
-@cindex classpath, dynamic
-@cindex dynamic classpath
-@cindex classpath, static
-@cindex static classpath
-@DOCSTRING(javaclasspath)
-
-@findex javaaddpath
-@cindex classpath, adding new path
-@cindex path, adding to classpath
-@cindex classpath, dynamic
-@cindex dynamic classpath, adding new path
-@DOCSTRING(javaaddpath)
-
-@cindex classpath, removing path
-@cindex path, removing from classpath
-@DOCSTRING(javarmpath)
-
-The following functions provide information and control over the interface
-between Octave and the Java Virtual Machine.
-
-@DOCSTRING(javachk)
-
-@DOCSTRING(usejava)
-
-@cindex memory, displaying Java memory status
-@DOCSTRING(javamem)
-
-@DOCSTRING(java_matrix_autoconversion)
-
-@DOCSTRING(java_unsigned_autoconversion)
-
-@DOCSTRING(debug_java)
+
+
diff -r a9f72f9200d4 -r 66e84d9b70e1 doc/interpreter/octave.texi
--- a/doc/interpreter/octave.texi	Sat Feb 18 00:05:26 2017 +0100
+++ b/doc/interpreter/octave.texi	Sat Feb 18 03:58:30 2017 +0100
@@ -877,10 +877,10 @@
 
 Java Interface
 
-* Java Interface Functions::
 * Making Java Classes Available::
-* Creating an Instance of a Java Class::
-* Handling Java Memory Limitations::
+* How to use Java from within Octave::
+* Passing parameters to the JVM::
+* Java Interface Functions::
 
 Test and Demo Functions
 
