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"

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

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