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.

: 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.

: javachk (feature)

: javachk (feature, caller)

: msg = javachk (…)

Проверяет наличие 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.

: usejava (feature)

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

Возможные значения:

"awt"

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

"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 из общей памяти компьютера (которая включает физическую 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 и управления памятью операционной системы.

: val = java_matrix_autoconversion ()

: old_val = java_matrix_autoconversion (new_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)

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

: debug_java (new_val, "local")

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

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

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