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, но только те, которые созданы с помощью javaObject, могут использовать функции Java. Перед использованием 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) ¶

Устанавливает значение поля name объекта Java obj в 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, …) ¶

Вызывает метод 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 определяет, доступны ли определенные Java-функциональности в сеансе Octave. Эта функция предназначена для скриптов, которые могут изменять свое поведение в зависимости от наличия Java или определенных функций Java-среды выполнения.

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

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

: tf = usejava (feature) ¶

Возвращает true, если Java-элемент feature доступен.

Возможные функциональности:

"awt"

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

"desktop"

Запущен интерактивный рабочий стол.

"jvm"

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

"swing"

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

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