# HG changeset patch
# User Ernst Reissner <rei3ner@arcor.de>
# Date 1471545503 -7200
#      Thu Aug 18 20:38:23 2016 +0200
# Node ID b62695da6cc162ba179c2eac64cc69fb71d061ba
# Parent  b660951b3cc443ace5e186d81556ae14d71fe97f
external.txi: java interface: completed section on type conversions

Aded subsections on java types, null values, void, strings...

diff -r b660951b3cc4 -r b62695da6cc1 doc/interpreter/external.txi
--- a/doc/interpreter/external.txi	Wed Aug 17 02:53:08 2016 +0200
+++ b/doc/interpreter/external.txi	Thu Aug 18 20:38:23 2016 +0200
@@ -2118,8 +2118,20 @@
 @subsection Type conversions between Java and Octave
 @cindex conversion 
 
-Java is a quite strictly typed language. 
-The so called @dfn{primitive types} are 
+@menu
+* Java types and Octave types::
+* The types octavejava and nullmatrix::
+* Conversion of Character types::
+* Conversion of Logical and Numerical types::
+@end menu
+
+@node Java types and Octave types
+@subsubsection Java types and Octave types
+@cindex Java, primitive types
+@cindex Java, reference types 
+
+In contrast to the Matlab languge, Java is a quite strictly typed language. 
+The most basic types called @dfn{primitive types} are 
 
 @itemize
 @item
@@ -2127,7 +2139,7 @@
 @item
 @code{double} and @code{float} 
 representing 64 bit and 32 bit floating point numbers 
-according to the standard IEEE 754 
+according to the standard IEEE 754, 
 @item
 @code{long}, @code{int}, @code{short} and @code{byte} 
 representing 64, 32, 16 and 8 bit signed integer numbers
@@ -2139,32 +2151,124 @@
 @end itemize
 
 Besides the @dfn{primitive types}, there are @dfn{reference types}. 
-Roughtly speaking, reference types are either @dfn{Object types} or
+Roughtly speaking, reference types are either @dfn{object types} or
 array types. 
 There is a single special value, @code{null}, 
 which is common to all reference types, 
 which represents the 'reference to nowhere'.
-
-For Java's primitive types, 
+Whereas primitive types represent simple instances,
+instances of reference types (@code{null} is no instance) 
+refer to more complex objects and provide object oriented features.
+Whereas the primitive types are fixed, 
+the programmer can define new object types by subclassing. 
+For each type @code{T} there is an array type @code{T[]} 
+containing elements of type @code{T}. 
+Java arrays are always one-dimensional but may be nested, 
+i.e. @code{T} may again be an array type. 
+
+For each primitive type, there is an according reference type, 
+the @dfn{wrapper type} 
+Conversions of a primitive type into its wrapper types 
+and the other way round are called 
+@dfn{boxing} and @dfn{unboxing}, respectively. 
+Both are performed mostly automatically. 
+Solely unboxing of @code{null} is undefined 
+and results in a @code{NullPointerException}.
+
+For Java's primitive types except @code{void}, 
 there are rough counterparts in Octave's type system. 
-The value @code{null} is represented by the empty matrix @code{[]} 
-with Octave type @code{null_matrix}. 
-
+@ref{tab:ConvTypes} associates Octave types returned by @code{class(.)}, 
+according primitive types and their wrappers in Java. 
+
+Java arrays are always one-dimensional 
+and multi-dimensional arrays are represented by nested one-dimensional arrays.
+Unlike in Octave, the indices start with @code{0}.
+
+
+
+@float Table,tab:ConvTypes
+@multitable{Octave Types}   {primitive Java Types}    {Java Wrapper Types}
+@headitem Octave Types  @tab primitive Java Types @tab Java Wrapper Types
+    @item logical       @tab boolean              @tab java.lang.Boolean 
+    @item double        @tab double               @tab java.lang.Double
+    @item single        @tab float                @tab java.lang.Float
+    @item int8,  uint8  @tab byte                 @tab java.lang.Byte 
+    @item int16, uint16 @tab short                @tab java.lang.Short
+    @item int32, uint32 @tab int                  @tab java.lang.Integer
+    @item int64, uint64 @tab long                 @tab java.lang.Long
+    @item int64, uint64 @tab long                 @tab java.lang.Long
+    @item char          @tab char                 @tab java.lang.Character
+@end multitable
+@caption{Octave types, 
+according Java non-@code{void} primitive types and their wrapper types}
+@end float
+
+
+@node The types octavejava and nullmatrix
+@subsubsection The types @code{octave_java} and @code{null_matrix}
+@cindex octave_java
+@cindex null_matrix
 
 
 The functions @code{javaObject} and @code{javaArray}
 create Java objects and return them
-wrapped in an instance of the Octave type @code{octave_java}.
+wrapped in an instance of the Octave type @code{octave_java}. 
+Note that the type of these objects 
+given by @code{typeinfo(.)} is @code{octave_java}, 
+whereas applying @code{class(.)} yields the Java class name. 
 
 Instances of type @code{octave_java} can be passed
 to the functions of the java interface
 like @code{java_set}, @code{java_get} and @code{javaMethod}.
 Of course Octave hands over to the JVM (Java Virtual Machine),
-not the instance of @code{octave_java} but the Java object wrapped therein.
-
-Passing @code{[]}, the @code{null_matrix} on the side of Octave, 
-is seen as @code{null} at Java's side. 
-
+not the instance of @code{octave_java} but the Java object wrapped
+therein.
+
+Accordingly, in general, @code{java_get} and @code{javaMethod} 
+return an instance of @code{octave_java} wrapping a java object. 
+
+Note that @code{octave_java} is never used to wrap @code{null}. 
+Instead, the value @code{null} at Java's side 
+is seen as @code{[]} on the side of Octave and the other way round. 
+Thus @code{[]} is a valid input argument for the functions of the Java interface
+and thus if a Java method invoked by @code{javaMethod} returns @code{null} 
+or if @code{java_get} queries a field value @code{null}, 
+in fact @code{[]} is passed to Octave. 
+If a method in Java has return type @code{void}, 
+@code{javaMethod} returns @code{[]} as well. 
+
+Note that the type of @code{[]} given by @code{typeinfo(.)} 
+is @code{null_matrix}, 
+whereas the class given by @code{class(.)} is @code{double}. 
+This seems not appropriate since in Java @code{null} 
+belongs to an arbitrary reference type and not to a special primitive type. 
+
+
+@node Conversion of Character types
+@subsubsection Conversion of Character types
+
+In Java single unicode-characters are kept in instances of @code{char}, 
+whereas typically sequences of characters are kept not in @code{char[]} 
+but in instances of the reference type @code{java.lang.String}. 
+A Java-string may of course also keep a single character. 
+Accordingly, in Octave, @code{'abcd'} is merely a shortcut 
+@code{['a' 'b' 'c' 'd']}. 
+Thus for formats @code{1xn} and @code{mx1} 
+and in particular @code{1x1} the Octave type @code{char} 
+is converted into the Java type @code{java.lang.String} 
+and the other way round. 
+
+For @code{m,n>1} in contrast, the Octave type @code{char} 
+is converted into the Java array type @code{java.lang.String[]} 
+and the other way round. 
+
+
+
+@node Conversion of Logical and Numerical types
+@subsubsection Conversion of Logical and Numerical types
+@cindex Java conversion logical, 
+@cindex Java conversion int64, uint64, int32, uint32, int16, uint16, int8, uint8
+@cindex Java conversion double, single
 
 It is also possible, to pass arguments of Octave types
 given in the first column of @ref{tab:ConvTypes}.
@@ -2172,21 +2276,6 @@
 specified in the second column of @ref{tab:ConvTypes} 
 before being passed to the JVM. 
 
-
-@float Table,tab:ConvTypes
-@multitable{Octave Types} {primitive Java Types} {Java Wrapper Types}
-@headitem Octave Types @tab primitive Java Types @tab Java Wrapper Types
-@item       scalar  @tab double  @tab java.lang.Double
-@item float scalar  @tab float   @tab java.lang.Float
-@item bool          @tab boolean @tab java.lang.Boolean 
-@item int8,  uint8  @tab byte    @tab java.lang.Byte 
-@item int16, uint16 @tab short   @tab java.lang.Short
-@item int32, uint32 @tab int     @tab java.lang.Integer
-@item int64, uint64 @tab long    @tab java.lang.Long
-@end multitable
-@caption{Octave types, according Java primitive types and their wrapper types}
-@end float
-
 Let us consider @ref{tab:ConvTypes} in more detail: 
 Since the 64 bit floating point types @code{scalar} and @code{double} 
 both conform fairly with the standard IEEE 754, 
@@ -2288,8 +2377,6 @@
 also for numeric types, to save memory. 
 
 
-
-
 @node Handling Java memory limitations
 @subsection Handling Java memory limitations
 @cindex memory, limitations
