Java接口函数 (GNU Octave(版本11.1.0))

A.4.4 Java接口函数¶

以下函数是Java接口的核心。它们提供了一种创建Java对象、获取和设置其数据字段以及调用Java方法的方式，这些方法将结果返回给Octave。

jobj = javaObject (classname) ¶

jobj = javaObject (classname, arg1, …) ¶

创建类 classname 的Java对象，通过使用参数 arg1, ... 调用类的构造函数。

下面的第一个示例创建了一个未初始化的对象，而第二个示例为构造函数提供了一个初始参数。

x = javaObject ("java.lang.StringBuffer")
x = javaObject ("java.lang.StringBuffer", "Initial string")

另请参阅: javaMethod, javaArray.

jary = javaArray (classname, sz) ¶

jary = javaArray (classname, m, n, …) ¶

创建一个大小为 sz、元素类型为 classname 类的Java数组。

classname 可以是表示某个类的Java对象，也可以是包含完全限定类名的字符串。对象的大小也可以通过单独的整数参数 m, n 等来指定。

生成的数组未初始化。如果 classname 是引用类型，则所有元素置为null；如果 classname 是基本数据类型，则所有元素置为默认值（通常为0）。

示例代码:

jary = javaArray ("java.lang.String", 2, 2);
jary(1,1) = "Hello";

另请参阅: javaObject.

Octave中有许多不同的变量类型，但只有通过 javaObject 创建的对象才能使用Java函数。在对未知对象使用Java之前，可以使用 isjava 检查其类型。

tf = isjava (x) ¶

如果 x 是Java对象，则返回 true。

另请参阅: class, typeinfo, isa, javaObject.

一旦创建了对象，很自然地就要查找该对象具有哪些字段，并读取（get）和写入（set）这些字段。

在Octave中，结构体的 fieldnames 函数已被重载，可用于返回Java对象的字段。例如：

dobj = javaObject ("java.lang.Double", pi);
fieldnames (dobj)
⇒ 
{
  [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
}

对象与结构体的类比同样适用于读取和写入对象字段。要读取一个字段，可以使用结构体中带 ‘.’ 运算符的对象索引方式。这是读取字段的首选方法，但Octave也提供了通过 java_get 读取字段的函数接口。下面展示了两种方式的示例。

dobj = javaObject ("java.lang.Double", pi);
dobj.MAX_VALUE
⇒   1.7977e+308
java_get ("java.lang.Float", "MAX_VALUE")
⇒   3.4028e+38

val = java_get (obj, name) ¶

获取Java对象 obj 中字段 name 的值。

对于静态字段，obj 可以是表示相应类的完全限定名称的字符串。

当 obj 是常规Java对象时，可以使用类似结构体索引的方式作为快捷语法。例如，以下两个语句是等效的：

  java_get (x, "field1")
  x.field1

另请参阅: java_set, javaMethod, javaObject.

obj = java_set (obj, name, val) ¶

将Java对象 obj 中字段 name 的值设置为 val。

对于静态字段，obj 可以是表示相应Java类的完全限定名称的字符串。

当 obj 是常规Java对象时，可以使用类似结构体索引的方式作为快捷语法。例如，以下两个语句是等效的：

  java_set (x, "field1", val)
  x.field1 = val

另请参阅: java_get, javaMethod, javaObject.

要查看对象可以调用哪些方法，请使用 methods。例如，使用之前创建的 dobj：

methods (dobj)
⇒ 
Methods for class java.lang.Double:
boolean equals(java.lang.Object)
java.lang.String toString(double)
java.lang.String toString()
...

要调用对象的方法，使用同样的结构体索引运算符 ‘.’。Octave还通过 javaMethod 提供了调用对象方法的函数接口。下面展示了两种方式的示例。

dobj = javaObject ("java.lang.Double", pi);
dobj.equals (3)
⇒   0
javaMethod ("equals", dobj, pi)
⇒   1

ret = javaMethod (methodname, obj) ¶

ret = javaMethod (methodname, obj, arg1, …) ¶

在Java对象 obj 上调用方法 methodname，参数为 arg1, ...

对于静态方法，obj 可以是表示相应类的完全限定名称的字符串。

当 obj 是常规Java对象时，可以使用类似结构体索引的方式作为快捷语法。例如，以下两个语句是等效的：

  ret = javaMethod ("method1", x, 1.0, "a string")
  ret = x.method1 (1.0, "a string")

javaMethod 返回方法调用的结果。

另请参阅: methods, javaObject.

以下三个函数用于显示和修改Java虚拟机使用的类路径。这与Octave的 PATH 变量完全无关，JVM使用该类路径来查找要执行的正确代码。

javaclasspath () ¶

dpath = javaclasspath () ¶

[dpath, spath] = javaclasspath () ¶

clspath = javaclasspath (what) ¶

以字符串元胞数组的形式返回Java虚拟机的类路径。

如果无输入参数调用：

如果没有请求输出，动态和静态类路径将被打印到标准输出。
如果请求一个输出值 dpath，结果为动态类路径。
如果请求两个输出值 dpath 和 spath，第一个变量将包含动态类路径，第二个变量将包含静态类路径。

如果使用单个输入参数 what 调用：

"-dynamic": 返回动态类路径。
"-static": 返回静态类路径。
"-all": 在单个字符串元胞数组中返回静态和动态类路径。

另请参阅: javaaddpath, javarmpath.

javaaddpath (clspath) ¶

javaaddpath (clspath1, …) ¶

javaaddpath ({clspath1, …}) ¶

javaaddpath (…, "-end") ¶

将 clspath 添加到Java虚拟机动态类路径的开头。

clspath 可以是存放 .class 文件的目录，或者是包含Java类的 .jar 文件。可以通过指定额外的参数或使用字符串的元胞数组同时添加多个路径。

如果最后一个参数是 "-end"，则将新元素追加到当前类路径的末尾。

另请参阅: javarmpath, javaclasspath.

javarmpath (clspath) ¶

javarmpath (clspath1, …) ¶

javarmpath ({clspath1, …}) ¶

从Java虚拟机的动态类路径中移除 clspath。

clspath 可以是存放 .class 文件的目录，或者是包含Java类的 .jar 文件。通过指定额外的参数或使用字符串的元胞数组，可以同时删除多个路径。

另请参阅: javaaddpath, javaclasspath.

以下函数提供Octave和Java虚拟机之间接口的信息和控制。

msg = javachk (feature) ¶

msg = javachk (feature, caller) ¶

检查 feature 在当前Octave会话中是否可用。如果 feature 不可用、未启用或无法识别，则返回一个带有 "message" 和 "identifier" 字段的标量结构体。

可能识别的功能包括：

"awt": 用于GUI的抽象窗口工具包（Abstract Window Toolkit）。
"desktop": 交互式桌面正在运行。
"jvm": Java虚拟机。
"swing": 用于轻量级GUI的Swing组件。

如果 feature 不受支持，将返回一个带有 "message" 和 "identifier" 字段的标量结构体。其中 "message" 字段包含一条错误消息，提到了 feature 和可选指定的用户 caller。此结构体可以传递给 error 函数使用。

如果 feature 受支持且可用，则返回一个带有 "message" 和 "identifier" 字段的空结构体数组。

javachk 用于确定Octave会话中是否有特定的Java功能可用。此函数是为需要根据Java可用性改变行为的脚本提供的。

兼容性说明：功能 "desktop" 永远不可用，因为Octave没有基于Java的桌面。

另请参阅: usejava, error.

tf = usejava (feature) ¶

如果Java元素 feature 可用则返回 true。

可能的功能包括：

"awt": 用于GUI的抽象窗口工具包（Abstract Window Toolkit）。
"desktop": 交互式桌面正在运行。
"jvm": Java虚拟机。
"swing": 用于轻量级GUI的Swing组件。

usejava 确定Octave会话中是否有特定的Java功能可用。此函数是为需要根据Java可用性改变行为的脚本提供的。功能 "desktop" 始终返回 false，因为Octave没有基于Java的桌面。如果Octave在编译时启用了Java接口并且安装了Java，则其他功能可能可用。

另请参阅: javachk.

javamem () ¶

jmem = javamem () ¶

显示Java虚拟机（JVM）的当前内存使用情况，并运行垃圾回收器。

当没有返回参数时，信息会打印到屏幕上。否则，输出元胞数组 jmem 包含最大内存（Maximum）、总内存（Total）和可用内存（Free）（以字节为单位）。

所有基于Java的例程都在JVM的共享内存池中运行，这是JVM从计算机总内存（包括物理RAM和硬盘上的虚拟内存/交换空间）中划分出来的一个专用且独立的内存部分。

最大允许内存使用量可以通过文件 java.opts 配置。此文件所在的目录由环境变量 OCTAVE_JAVA_DIR 决定。如果该变量未设置，则使用 javaaddpath.m 所在的目录（通常为 OCTAVE_HOME/share/octave/OCTAVE_VERSION/m/java/）。

java.opts 是一个纯文本文件，每行一个选项。默认的初始内存大小和默认的最大内存大小（两者都依赖于系统）可以像这样覆盖：

-Xms64m

-Xmx512m

（本例中以兆字节为单位）。如果系统的可用物理内存有限或出现Java内存错误，您可以根据自己的需求调整这些值。

"Total memory"（总内存）是操作系统当前分配给JVM的内存量，取决于实际和活动内存使用情况。"Free memory"（可用内存）不言自明。在运行基于Java的Octave函数期间，由于Java自身的清理和操作系统的内存管理，"Total memory"和"Free memory"的数量会发生变化。

val = java_matrix_autoconversion () ¶

old_val = java_matrix_autoconversion (new_val) ¶

old_val = java_matrix_autoconversion (new_val, "local") ¶