A.4.4 Функции Java-интерфейса

Следующие функции составляют основу Java-интерфейса. Они позволяют создавать объекты Java, получать и задавать их поля данных, а также вызывать методы Java, возвращающие результаты в Octave.

: jobj = javaObject (classname)

: jobj = javaObject (classname, arg1, …)

Создать объект Java класса classsname, вызвав конструктор класса с аргументами arg1, …

В первом примере ниже создается неинициализированный объект, а во втором в конструктор передается начальный аргумент.

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

См. также: javaMethod, javaArray.

: jary = javaArray (classname, sz)

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

Создать массив Java размера sz с элементами класса classname.

classname может быть объектом Java, представляющим класс, или строкой с полным именем класса. Размер объекта также можно задать отдельными целочисленными аргументами m, n и т. д.

Созданный массив не инициализирован. Всем элементам присваивается значение null, если classname является ссылочным типом, или значение по умолчанию (обычно 0), если classname является примитивным типом.

Пример кода:

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

См. также: javaObject.

В Octave есть множество различных типов переменных, но использовать функции Java могут только объекты, созданные с помощью javaObject. Перед использованием Java с объектом неизвестного типа его тип можно проверить с помощью isjava.

: tf = isjava (x)

Вернуть true, если x является объектом Java.

См. также: class, typeinfo, isa, javaObject.

После создания объекта естественно узнать, какие поля он содержит, а также прочитать (получить) и записать (задать) их.

В 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)

Получить значение поля name объекта Java obj.

Для статических полей obj может быть строкой, содержащей полное имя соответствующего класса.

Если obj — обычный объект Java, можно использовать индексирование, подобное индексированию структур, в качестве сокращенного синтаксиса. Например, следующие два выражения эквивалентны:

java_get (x, "field1")
  x.field1

См. также: java_set, javaMethod, javaObject.

: obj = java_set (obj, name, val)

Задать значение val для поля name объекта Java obj.

Для статических полей 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, …)

Вызвать метод methodname объекта Java obj с аргументами arg1, ….

Для статических методов obj может быть строкой, содержащей полное имя соответствующего класса.

Если obj — обычный объект Java, можно использовать индексирование, подобное индексированию структур, в качестве сокращенного синтаксиса. Например, следующие два выражения эквивалентны:

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

javaMethod возвращает результат вызова метода.

См. также: methods, javaObject.

Следующие три функции используются для отображения и изменения пути классов, используемого виртуальной машиной Java. Он полностью отделен от переменной PATH в Octave и используется JVM для поиска кода, который нужно выполнить.

: javaclasspath ()

: dpath = javaclasspath ()

: [dpath, spath] = javaclasspath ()

: clspath = javaclasspath (what)

Вернуть путь классов виртуальной машины Java в виде массива ячеек со строками.

При вызове без входных аргументов:

• Если выходные аргументы не запрошены, динамический и статический пути классов выводятся в стандартный поток вывода.
• Если запрошено одно выходное значение dpath, результатом будет динамический путь классов.
• Если запрошены два выходных значения — dpath и spath, первая переменная будет содержать динамический путь классов, а вторая — статический.

При вызове с одним входным параметром what:

"-dynamic"

Вернуть динамический путь классов.

"-static"

Вернуть статический путь классов.

"-all"

Вернуть статический и динамический пути классов в одном массиве ячеек типа cellstr.

См. также: javaaddpath, javarmpath.

: javaaddpath (clspath)

: javaaddpath (clspath1, …)

: javaaddpath ({clspath1, …})

: javaaddpath (…, "-end")

Добавить clspath в начало динамического пути классов виртуальной машины Java.

clspath может быть каталогом с файлами .class или файлом .jar, содержащим классы Java. Несколько путей можно добавить одновременно, указав дополнительные аргументы или используя массив ячеек со строками.

Если последний аргумент — "-end", новый элемент добавляется в конец текущего пути классов.

См. также: javarmpath, javaclasspath.

: javarmpath (clspath)

: javarmpath (clspath1, …)

: javarmpath ({clspath1, …})

Удалить clspath из динамического пути классов виртуальной машины Java.

clspath может быть каталогом с файлами .class или файлом .jar, содержащим классы Java. Несколько путей можно удалить одновременно, указав дополнительные аргументы или используя массив ячеек со строками.

См. также: javaaddpath, javaclasspath.

Следующие функции предоставляют сведения об интерфейсе между Octave и виртуальной машиной Java и позволяют управлять им.

: msg = javachk (feature)

: msg = javachk (feature, caller)

Проверить наличие функции Java feature в текущем сеансе. Вернуть структуру ошибки, если feature недоступна, отключена или не распознана.

Распознаются следующие функции:

"awt"

Abstract Window Toolkit для графических интерфейсов.

"desktop"

Интерактивная среда рабочего стола запущена.

"jvm"

Виртуальная машина Java.

"swing"

Компоненты Swing для облегченных графических интерфейсов.

Если feature не поддерживается, возвращается скалярная структура с полями "message" и "identifier". Поле "message" содержит сообщение об ошибке, в котором упоминается feature, а также необязательный указанный пользователем caller. Эту структуру можно передать функции error.

Если feature поддерживается и доступна, возвращается пустой массив структур с полями "message" и "identifier".

javachk определяет, доступны ли в сеансе Octave определенные функции Java. Эта функция предназначена для сценариев, которые могут изменять свое поведение в зависимости от доступности Java или определенных возможностей среды выполнения Java.

Примечание о совместимости: функция "desktop" недоступна никогда, поскольку в Octave нет рабочего стола на основе Java.

См. также: usejava, error.

: tf = usejava (feature)

Вернуть true, если функция Java feature доступна.

Возможны следующие функции:

"awt"

Abstract Window Toolkit для графических интерфейсов.

"desktop"

Интерактивная среда рабочего стола запущена.

"jvm"

Виртуальная машина Java.

"swing"

Компоненты Swing для облегченных графических интерфейсов.

usejava определяет, доступны ли в сеансе Octave определенные функции Java. Эта функция предназначена для сценариев, которые могут изменять свое поведение в зависимости от доступности Java. Функция "desktop" всегда возвращает false, поскольку в Octave нет рабочего стола на основе Java. Другие функции могут быть доступны, если Octave был собран с Java-интерфейсом и Java установлена.

См. также: javachk.

: javamem ()

: jmem = javamem ()

Показать текущее использование памяти виртуальной машиной Java (JVM) и запустить сборщик мусора.

Если выходной аргумент не указан, сведения выводятся на экран. В противном случае выходной массив ячеек jmem содержит максимальный, общий и свободный объем памяти (в байтах).

Все процедуры на основе Java выполняются в общей области памяти JVM — выделенной отдельной части памяти, которую JVM берет из общей памяти компьютера (физической ОЗУ и виртуальной памяти / файла подкачки на жестком диске).

Максимально допустимый объем используемой памяти можно настроить с помощью файла 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" говорит само за себя. Во время работы функций Octave на основе Java объем общей и свободной памяти меняется из-за очистки памяти самой Java и управления памятью операционной системой.

: val = java_matrix_autoconversion ()

: old_val = java_matrix_autoconversion (new_val)

: old_val = java_matrix_autoconversion (new_val, "local")

Запросить или задать внутреннюю переменную, управляющую автоматическим преобразованием массивов Java в матрицы Octave.

Значение по умолчанию — false.

При вызове из функции с параметром "local" переменная изменяется локально для этой функции и всех вызываемых ею подпрограмм. Исходное значение переменной восстанавливается при выходе из функции.

См. также: java_unsigned_autoconversion, debug_java.

: val = java_unsigned_autoconversion ()

: old_val = java_unsigned_autoconversion (new_val)

: old_val = java_unsigned_autoconversion (new_val, "local")

Запросить или задать внутреннюю переменную, управляющую преобразованием целочисленных классов, если включен параметр java_matrix_autoconversion.

Если эта функция включена, массивы Java классов Byte или Integer преобразуются в матрицы классов uint8 или uint32 соответственно. Значение по умолчанию — true.

При вызове из функции с параметром "local" переменная изменяется локально для этой функции и всех вызываемых ею подпрограмм. Исходное значение переменной восстанавливается при выходе из функции.

См. также: java_matrix_autoconversion, debug_java.

: val = debug_java ()

: old_val = debug_java (new_val)

: old_val = debug_java (new_val, "local")

Запросить или задать внутреннюю переменную, определяющую, выводятся ли дополнительные отладочные сведения об инициализации JVM и исключениях Java.

При вызове из функции с параметром "local" переменная изменяется локально для этой функции и всех вызываемых ею подпрограмм. Исходное значение переменной восстанавливается при выходе из функции.

См. также: java_matrix_autoconversion, java_unsigned_autoconversion.