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"

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

См. также: 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.