Mercurial > hg > octave-nkf
changeset 19099:9887440ceb2e stable
doc: Update documentation around java_get, java_set.
* NEWS: Don't include java_get, java_set in list of functions deprecated in
3.8.
* java.txi: Add java_get, java_set to manual. Write documentation for using
'.' operator to read/write fields of object. Add examples of using Java
interface.
* java_get.m, java_set.m: Change @deftypefn type to "Function File".
| author | Rik <rik@octave.org> |
|---|---|
| date | Sun, 13 Jul 2014 17:43:19 -0700 |
| parents | 10c38b9e5423 |
| children | eea4f61960d4 bebe22d2cb58 |
| files | NEWS doc/interpreter/java.txi scripts/java/java_get.m scripts/java/java_set.m |
| diffstat | 4 files changed, 101 insertions(+), 34 deletions(-) [+] |
line wrap: on
line diff
--- a/NEWS +++ b/NEWS @@ -320,12 +320,13 @@ directly from Octave: debug_java java_matrix_autoconversion - isjava java_unsigned_autoconversion - java2mat javaaddpath - javaArray javaclasspath - javaMethod javamem - javaObject javarmpath - usejava + isjava java_set + java2mat java_unsigned_autoconversion + javaArray javaaddpath + javaMethod javaclasspath + javaObject javamem + java_get javarmpath + usejava In addition, the following functions that use the Java interface are now available (provided that Octave is compiled with support for @@ -369,16 +370,14 @@ be removed from Octave 3.12 (or whatever version is the second major release after 3.8): - default_save_options java_new - gen_doc_cache java_set - interp1q java_unsigned_conversion - isequalwithequalnans javafields - java_convert_matrix javamethods - java_debug re_read_readline_init_file - java_get read_readline_init_file - java_invoke saving_history - - + default_save_options java_new + gen_doc_cache java_unsigned_conversion + interp1q javafields + isequalwithequalnans javamethods + java_convert_matrix re_read_readline_init_file + java_debug read_readline_init_file + java_invoke saving_history + The following keywords have been deprecated in Octave 3.8 and will be removed from Octave 3.12 (or whatever version is the second major release after 3.8):
--- a/doc/interpreter/java.txi +++ b/doc/interpreter/java.txi @@ -48,30 +48,98 @@ @cindex object, creating a Java object @DOCSTRING(javaObject) -@cindex fields, displaying available fields of a Java object -@strong{FIXME:} Need documentation on how fieldnames() is overloaded to return -the methods of a Java object. +@cindex array, creating a Java array +@DOCSTRING(javaArray) -@cindex field, returning value of Java object field -@strong{FIXME:} Need documentation on how to use structure-like indexing -to get fields from Java object. - -@cindex field, setting value of Java object field -@strong{FIXME:} Need documentation on how to use structure-like indexing -to set fields from Java object. +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) -@cindex array, creating a Java array -@DOCSTRING(javaArray) +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) -@cindex methods, displaying available methods of a Java object -@strong{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
--- a/scripts/java/java_get.m +++ b/scripts/java/java_get.m @@ -17,7 +17,7 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Loadable Function} {@var{val} =} java_get (@var{obj}, @var{name}) +## @deftypefn {Function File} {@var{val} =} java_get (@var{obj}, @var{name}) ## Get the value of the field @var{name} of the Java object @var{obj}. For ## static fields, @var{obj} can be a string representing the fully qualified ## name of the corresponding class.
--- a/scripts/java/java_set.m +++ b/scripts/java/java_set.m @@ -17,7 +17,7 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Loadable Function} {@var{obj} =} java_set (@var{obj}, @var{name}, @var{val}) +## @deftypefn {Function File} {@var{obj} =} java_set (@var{obj}, @var{name}, @var{val}) ## Set the value of the field @var{name} of the Java object @var{obj} to ## @var{val}. For static fields, @var{obj} can be a string representing the ## fully qualified named of the corresponding Java class.